Skip to content

Disable Poetry "package mode" #603

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 19, 2025
Merged

Disable Poetry "package mode" #603

merged 1 commit into from
Jun 19, 2025

Conversation

per1234
Copy link
Contributor

@per1234 per1234 commented Jun 19, 2025

Project Python package dependencies are managed using the Poetry tool.

By default, Poetry is configured in "package mode", which is intended for use with projects that are a Python package. When Poetry is used in a project like this that is a standalone script, this configuration is in appropriate and has the following effects:

Installing the project as a package is completely inappropriate if the project is not a package, and may cause the command to fail with a cryptic error. This can be avoided by passing the --no-root flag to the install command, but that increases the usage complexity and chance for user error.

Although metadata fields under the tool.poetry section of the pyproject.toml configuration file are important for a package, in a non-package project there are better ways to provide that information. Since Git tags are used for versioning, the presence of a version field is especially harmful since it means duplication of information and extra work for the project maintainer (and likelihood the metadata will not be kept updated).

This "package mode" can be disabled via the pyproject.toml configuration file, which causes Poetry to operate purely in the sole capacity in which it is used by the templates: to manage tool dependencies.

The project Python package dependencies are managed using the Poetry tool.

By default, Poetry is configured in "package mode", which is intended for use with projects that are a Python package.
When Poetry is used in a project like this that is a standalone script, this configuration is inappropriate and has the
following effects:

* `poetry install` command installs the project as a Python package in addition to the dependencies.
* `name`, `version`, `description`, and `authors` fields of the pyproject.toml file are required.

Installing the project as a package is completely inappropriate if the project is not a package, and may cause the
command to fail with a cryptic error. This can be avoided by passing the `--no-root` flag to the `install` command, but
that increases the usage complexity and chance for user error.

Although metadata fields under the `tool.poetry` section of the pyproject.toml configuration file are important for a
package, in a non-package project there are better ways to provide that information. Since Git tags are used for
versioning, the presence of a `version` field is especially harmful since it means duplication of information and extra
work for the project maintainer (and likelihood the metadata will not be kept updated).

This "package mode" can be disabled via the pyproject.toml configuration file, which causes Poetry to operate purely in
the sole capacity in which it is used by the templates: to manage dependencies.
@per1234 per1234 self-assigned this Jun 19, 2025
@per1234 per1234 added type: enhancement Proposed improvement topic: code Related to content of the project itself topic: infrastructure Related to project infrastructure labels Jun 19, 2025
@per1234 per1234 merged commit 5354160 into arduino:main Jun 19, 2025
22 checks passed
@per1234 per1234 deleted the package-mode branch June 19, 2025 15:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
topic: code Related to content of the project itself topic: infrastructure Related to project infrastructure type: enhancement Proposed improvement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant